<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Pin: REPLAY</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Pin
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">REPLAY<div class="ingroups"><a class="el" href="group__API__REF.html">Instrumentation API Reference</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gadd939297fe51b34aedcbcb8b627a89f2"><td class="memItemLeft" align="right" valign="top">IMG&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__REPLAY.html#gadd939297fe51b34aedcbcb8b627a89f2">IMG_CreateAt</a> (const char *filename, ADDRINT start, USIZE size, ADDRINT loadOffset, BOOL mainExecutable)</td></tr>
<tr class="separator:gadd939297fe51b34aedcbcb8b627a89f2"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga07759b799516b378bd7f3faa0a0a8325"><td class="memItemLeft" align="right" valign="top">VOID&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__REPLAY.html#ga07759b799516b378bd7f3faa0a0a8325">IMG_ReplayImageLoad</a> (IMG img)</td></tr>
<tr class="separator:ga07759b799516b378bd7f3faa0a0a8325"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga56cbe508bdf0333f5427112711699e9c"><td class="memItemLeft" align="right" valign="top">VOID&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__REPLAY.html#ga56cbe508bdf0333f5427112711699e9c">PIN_ReplayContextChange</a> (<a class="el" href="group__THREADS.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid, const <a class="el" href="structCONTEXT.html">CONTEXT</a> *from, <a class="el" href="structCONTEXT.html">CONTEXT</a> *to, <a class="el" href="group__PIN__CONTROL.html#ga8e4e6511a0e09fdc5ec7d6dbf395b3a8">CONTEXT_CHANGE_REASON</a> reason, INT32 info)</td></tr>
<tr class="separator:ga56cbe508bdf0333f5427112711699e9c"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga67068d9c22e4da2fb9522098dcf18bde"><td class="memItemLeft" align="right" valign="top">VOID&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__REPLAY.html#ga67068d9c22e4da2fb9522098dcf18bde">IMG_ReplayImageUnload</a> (IMG img)</td></tr>
<tr class="separator:ga67068d9c22e4da2fb9522098dcf18bde"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga66fc4a31f4b1b0ac74fef23c08bf759d"><td class="memItemLeft" align="right" valign="top">BOOL&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__REPLAY.html#ga66fc4a31f4b1b0ac74fef23c08bf759d">PIN_WasMemoryReservedInLoadTime</a> ()</td></tr>
<tr class="separator:ga66fc4a31f4b1b0ac74fef23c08bf759d"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h2 class="groupheader">Function Documentation</h2>
<a id="gadd939297fe51b34aedcbcb8b627a89f2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gadd939297fe51b34aedcbcb8b627a89f2">&#9670;&nbsp;</a></span>IMG_CreateAt()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">IMG IMG_CreateAt </td>
          <td>(</td>
          <td class="paramtype">const char *&#160;</td>
          <td class="paramname"><em>filename</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">ADDRINT&#160;</td>
          <td class="paramname"><em>start</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">USIZE&#160;</td>
          <td class="paramname"><em>size</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">ADDRINT&#160;</td>
          <td class="paramname"><em>loadOffset</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">BOOL&#160;</td>
          <td class="paramname"><em>mainExecutable</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Static model for instrumenting IMG's once they are loaded into memory.</p>
<p>Returns a IMG object for image loaded outside of PIN's loader. Tool should use this IMG object to mark the routines inside it, using <a class="el" href="group__RTN.html#gad780d7c43d06f2197051a05ffb7f7b96">RTN_CreateAt()</a>. After all the routines are marked, tool should call <a class="el" href="group__REPLAY.html#ga07759b799516b378bd7f3faa0a0a8325">IMG_ReplayImageLoad()</a> to finalize the image load procedure.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">filename</td><td>name of the image visible to Pin tools </td></tr>
    <tr><td class="paramname">start</td><td>memory address where first byte of the image is loaded to </td></tr>
    <tr><td class="paramname">size</td><td>the size of the image in memory. This means that the image region in memory will be at [start .. start+size) </td></tr>
    <tr><td class="paramname">loadOffset</td><td>the offset between the memory addresses specified in the executable/library files and the memory addresses where this image was actaully loaded </td></tr>
    <tr><td class="paramname">mainImage</td><td>TRUE if this is the main image</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>IMG object that represents the image. Please make sure to call <a class="el" href="group__REPLAY.html#ga07759b799516b378bd7f3faa0a0a8325">IMG_ReplayImageLoad()</a> on the IMG object after you're done creating all the routines in the IMG object.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: All<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
<a id="ga07759b799516b378bd7f3faa0a0a8325"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga07759b799516b378bd7f3faa0a0a8325">&#9670;&nbsp;</a></span>IMG_ReplayImageLoad()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID IMG_ReplayImageLoad </td>
          <td>(</td>
          <td class="paramtype">IMG&#160;</td>
          <td class="paramname"><em>img</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Replays the image load of an IMG object (created by <a class="el" href="group__REPLAY.html#gadd939297fe51b34aedcbcb8b627a89f2">IMG_CreateAt()</a>). This means that all the image load callbacks will be called for the specified IMG object. If <a class="el" href="group__PIN__CONTROL.html#gab466cd00518ff315446c92f98f7ea1a0">PIN_StartProgram()</a> wasn't called yet, PIN will enqueue this request and will process this request after <a class="el" href="group__PIN__CONTROL.html#gab466cd00518ff315446c92f98f7ea1a0">PIN_StartProgram()</a> was called</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">img</td><td>The image object to replay its load</td></tr>
  </table>
  </dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The vm and pin client locks are obtained during the call of this API.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: All<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
<a id="ga67068d9c22e4da2fb9522098dcf18bde"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga67068d9c22e4da2fb9522098dcf18bde">&#9670;&nbsp;</a></span>IMG_ReplayImageUnload()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID IMG_ReplayImageUnload </td>
          <td>(</td>
          <td class="paramtype">IMG&#160;</td>
          <td class="paramname"><em>img</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Ask Pin to perform all the functions it would normally do when it detects that a shared library has been unloaded. This is intended for use in a replay system, where the replay tool has recorded library unload operations, and now wants to replay them.</p>
<p>Note that a replay system need not explicitly call this function to cause image unload callbacks at the end of process execution. Pin will generate those callbacks itself provided that images were created using the <a class="el" href="group__REPLAY.html#ga07759b799516b378bd7f3faa0a0a8325">IMG_ReplayImageLoad</a> call. However, this function is required to handle explicit image unloads (for instance those caused by <code>dlclose()</code> )</p>
<p>IMG_ReplayImageUnload can be called from analysis or callback routines. If called from an analysis routine, the Pin client lock must be claimed before calling IMG_ReplayImageUnload (the Pin client lock is already held when in a callback routine, so there is no need to claim it again).</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">img</td><td>the IMG to be unloaded</td></tr>
  </table>
  </dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The pin client lock is obtained during the call of this API.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux (others to follow)<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
<a id="ga56cbe508bdf0333f5427112711699e9c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga56cbe508bdf0333f5427112711699e9c">&#9670;&nbsp;</a></span>PIN_ReplayContextChange()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID PIN_ReplayContextChange </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__THREADS.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a>&#160;</td>
          <td class="paramname"><em>tid</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="structCONTEXT.html">CONTEXT</a> *&#160;</td>
          <td class="paramname"><em>from</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="structCONTEXT.html">CONTEXT</a> *&#160;</td>
          <td class="paramname"><em>to</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__PIN__CONTROL.html#ga8e4e6511a0e09fdc5ec7d6dbf395b3a8">CONTEXT_CHANGE_REASON</a>&#160;</td>
          <td class="paramname"><em>reason</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">INT32&#160;</td>
          <td class="paramname"><em>info</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>This API is intended for use by tools that replay the execution of an application and need to replay an asynchronous context change that was received by the application at record time. This API is not intended as a general way to send a forced context change (signal, exception, APC) to the application. To do that, see <a class="el" href="group__EXCEPTION.html#ga35d13dc3ce578945eda8228b0db1c138">PIN_RaiseException()</a>.</p>
<p>Calling this API causes Pin to call back on the tool's context-changed notification function if one was set up with <a class="el" href="group__PIN__CONTROL.html#ga1cc0f28140cb83a035ebabdddf81861f">PIN_AddContextChangeFunction()</a>. Thus, the tool is notified about the context change as though the application really received it. Calling this API may also notify an external debugger if one is attached to Pin via the -appdebug switch, which gives the debugger a chance to stop execution of the application when it receives the replayed context change. (Whether this happens depends on the CONTEXT_CHANGE_REASON, and the expected behavior of the debugger on different platforms).</p>
<p><a class="el" href="group__REPLAY.html#ga56cbe508bdf0333f5427112711699e9c">PIN_ReplayContextChange()</a> does not return to its caller. If the <em>to</em> parameter is not NULL, execution resumes at that context after it has been potentially modified by the tool's context-changed call-back. If <em>reason</em> is CONTEXT_CHANGE_REASON_FATALSIGNAL, Pin emulates a fatal signal and execution terminates gracefully after calling the tool's Fini functions.</p>
<p>This API can be called from an analysis routine or a replacement routine, but not from a callback.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>The ID of the calling thread. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">from</td><td>The register state prior to the context change (e.g. the register state at the point when the signal is received for CONTEXT_CHANGE_REASON_SIGNAL). </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">to</td><td>The register state immediately after the context change. This should be NULL for CONTEXT_CHANGE_REASON_FATALSIGNAL. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">reason</td><td>The type of the context change. <br  />
 </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">info</td><td>Additional information, depending on <em>reason</em>. (Ignored for <em>reason</em> codes not listed below.) <ul>
<li>CONTEXT_CHANGE_REASON_FATALSIGNAL: The Unix signal number. </li>
<li>CONTEXT_CHANGE_REASON_SIGNAL: The Unix signal number. </li>
<li>CONTEXT_CHANGE_REASON_EXCEPTION: The Windows exception code. </li>
</ul>
</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>This function does not return.</dd></dl>
<dl class="section note"><dt>Note</dt><dd>The vm and pin client locks are obtained during the call of this API.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux &amp; Windows<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
<a id="ga66fc4a31f4b1b0ac74fef23c08bf759d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga66fc4a31f4b1b0ac74fef23c08bf759d">&#9670;&nbsp;</a></span>PIN_WasMemoryReservedInLoadTime()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">BOOL PIN_WasMemoryReservedInLoadTime </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Return TRUE if PIN was successfully reserved the neccessary memory at application load time (specified on the -reserve_memory knob), and was successfully restricted the memory from the loader (specified on the -restrict_memory knob). It is guaranteed this is the return value is FALSE then none the memory specified in the mentioned knobs was reserved/restricted</p>
<dl class="section return"><dt>Returns</dt><dd>TRUE if all the memory was reserved/restricted</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
